/*

   **********************************************************************
   *                                                                    *
   * This file contains the code for an image object for a content-     *
   * based image retrieval application that "summarizes" an image and   *
   * sends the resulting image "signature" to a server for              *
   * classification. The server returns the classification result in    *
   * the form of a Web page containing example images of the input      *
   * image's category.                                                  *
   *                                                                    *
   * The image class defined here is rather specific to this particular *
   * application and is not really designed for broad reuse (just yet). *
   *                                                                    *
   **********************************************************************
*/

/*
   **********************************************************************
   *                                                                    *
   * Gist   -- content-based image retrieval application for the gPhone *
   *                                                                    *
   * Copyright (C) 2011 Yong Zeng                                       *
   *                                                                    *
   * This file is part of Gist.                                       *
   *                                                                    *
   * Gist is free software; you can redistribute it and/or modify it  *
   * under the terms of the GNU General Public License as published by  *
   * the Free Software Foundation; either version 2 of the License, or  *
   * (at your option) any later version.                                *
   *                                                                    *
   * Gist is distributed in the hope that it will be useful, but      *
   * WITHOUT ANY WARRANTY; without even the implied warranty of         *
   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU   *
   * General Public License for more details.                           *
   *                                                                    *
   * You should have received a copy of the GNU General Public License  *
   * along with Goggle; if not, write to the Free Software Foundation,  *
   * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.       *
   *                                                                    *
   **********************************************************************
*/

//----------------------- PACKAGE SPECIFICATION -------------------------

package vision.gistcomputing ;

//------------------------------ IMPORTS --------------------------------

//------------------------- CLASS DEFINITION ----------------------------

/**
   This class implements a singleton settings object that can be used by
   different parts of the application for retrieving various
   user-specifiable parameters.
*/
class Settings {

/// The Goggle application's settings are shared across its various
/// activities using the shared preferences mechanism provided by
/// Android. In order to effect proper sharing, we have to name the
/// settings.
public final static String NAME = "goggle_settings" ;

/// The Android shared preferences mechanism stores key-value pairs
/// persistently across invocations. These strings act as the keys for
/// the different settings recognized by the Goggle application.
///@{
public final static String GIST_ESTIMATOR = "gist_estimator" ;
public final static String SERVER_ADDRESS = "server_address" ;
public final static String UPLOAD_POLICY  = "upload_policy" ;
///@}

/// The upload policy can be one of these values.
///@{
public final static int SEND_ENTIRE_IMAGE = 1 ;
public final static int SEND_GIST_VECTOR  = 2 ;
///@}

/// These are the default values for the above settings.
///@{
private final static String DEFAULT_GIST_ESTIMATOR = "GistEstimatorStub" ;
private final static String DEFAULT_SERVER_ADDRESS = "192.168.0.1" ;
private final static int    DEFAULT_UPLOAD_POLICY  = SEND_ENTIRE_IMAGE ;
///@}

/// These are the current values for the Goggle application's settings.
///@{
private String m_gist_estimator ;
private String m_server_address ;
private int    m_upload_policy ;
///@}

/// The full path name of the file containing the SIFT vocabulary.
///
/// This is really not an end-user setting. It is available to allow the
/// BBoF estimator to get this value without having to worry about an
/// Android context.
private String m_vocabulary_file ;

/// The settings object is a singleton. This member is the lone instance
/// of this class.
private static Settings m_instance = new Settings() ;

//-------------------------- INITIALIZATION -----------------------------

/// A private constructor because the settings object is a singleton.
private Settings()
{
   m_gist_estimator = DEFAULT_GIST_ESTIMATOR ;
   m_server_address = DEFAULT_SERVER_ADDRESS ;
   m_upload_policy  = DEFAULT_UPLOAD_POLICY ;
}

/// This method returns the lone instance of the settings object.
public static Settings instance()
{
   return m_instance ;
}

//------------------------ RETRIEVING SETTINGS --------------------------

/// This method returns the current value of the gist estimator setting,
/// which specifies the name of the algorithm to use to compute gist
/// vectors for input images.
public final static String gist_estimator()
{
   return m_instance.m_gist_estimator ;
}

/// This method returns the current value of the server address setting,
/// which specifies the IP address (or hostname if that is available) of
/// the Goggle server, i.e., the host that will perform the scene
/// classification task given the input image's gist vector. This server
/// is contacted over HTTP and its result is displayed as a Web page.
public final static String server_address()
{
   return m_instance.m_server_address ;
}

/// This method returns the current value of the upload policy, which
/// specifies whether the entire image or only its gist vector should be
/// sent to the server for classification.
public final static int upload_policy()
{
   return m_instance.m_upload_policy ;
}

/// This is a convenience method for querying the upload policy setting.
public final static boolean send_entire_image()
{
   return m_instance.m_upload_policy == SEND_ENTIRE_IMAGE ;
}

/// This is a convenience method for querying the upload policy setting.
public final static boolean send_gist_vector()
{
   return m_instance.m_upload_policy == SEND_GIST_VECTOR ;
}

/// This method returns the current value of the vocabulary file setting,
/// which specifies the full path name of the file containing the SIFT
/// vocabulary for use by the BBoF esitimator. This setting is not really
/// meant for end-users and so does not have a corresponding UI element
/// in the SettingsActivity. It is necessitated by the fact that the BBoF
/// estimator, being a purely computational object rather than part of
/// the Android framework, does not have a valid context to work with and
/// so needs to know the full path name of the vocabulary file, which can
/// only really be known by some object that really is tied into the
/// Android hierarchy.
public final static String vocabulary_file()
{
   return m_instance.m_vocabulary_file ;
}

//------------------------ MODIFYING SETTINGS ---------------------------

/// This method sets the gist estimator setting to the specified value.
/// This setting specifies the name of the algorithm to use for computing
/// gist vectors and should be a valid name as listed in the gist
/// estimator registry module.
///
/// NOTE: This method is meant to be called *only* by SettingsActivity.
final static void gist_estimator(String s)
{
   m_instance.m_gist_estimator = s ;
}

/// This method sets the server address setting to the specified value.
/// This setting points to the Goggle server, which is contacted over
/// HTTP.
///
/// WARNING: No validity/sanity checks are performed on the string
/// argument passed to this function! It had better be a valid IP address
/// or hostname.
///
/// NOTE: This method is meant to be called *only* by SettingsActivity.
final static void server_address(String s)
{
   m_instance.m_server_address = s ;
}

/// This method sets the upload policy setting to the specified value.
/// This setting governs whether the phone will send the entire image or
/// just its gist vector to the server for classification.
///
/// NOTE: This method is meant to be called *only* by SettingsActivity.
final static void upload_policy(int p)
{
   m_instance.m_upload_policy = p ;
}

/// This method sets the name of the vocabulary file for use by the BBoF
/// estimator. It doesn't really have any UI. It's just put here because
/// the estimator doesn't have an Android context and so needs to know
/// the full path name of vocabulary file.
///
/// NOTE: This method is meant to be called *only* by MainActivity.
final static void vocabulary_file(String full_path_name)
{
   m_instance.m_vocabulary_file = full_path_name ;
}

//-----------------------------------------------------------------------

} 
